Crate eventsourced

Event sourced entities.

EventSourced is inspired to a large degree by the amazing Akka Persistence library. It provides a framework for implementing Event Sourcing and CQRS.

The EventSourced trait defines the event type and handling for event sourced entities. These are identifiable by a type name and ID and can be created with the EventSourcedExt::entity extension method. Commands can be defined via the Command trait which contains a command handler function to either reject a command or return an event. An event gets persisted to the event log and then applied to the event handler to return the new state of the entity.

                 ┌───────┐   ┌ ─ ─ ─ Entity─ ─ ─ ─
                 │Command│                        │
┌ ─ ─ ─ ─ ─ ─    └───────┘   │ ┌────────────────┐
    Client   │────────────────▶│ handle_command │─┼─────────┐
└ ─ ─ ─ ─ ─ ─                │ └────────────────┘           │
       ▲                           │    │         │         │ ┌─────┐
        ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─     │read               │ │Event│
                  ┌─────┐               ▼         │         ▼ └─────┘
                  │Reply│    │     ┌─────────┐       ┌ ─ ─ ─ ─ ─ ─
                  │  /  │          │  State  │    │     EventLog  │
                  │Error│    │     └─────────┘       └ ─ ─ ─ ─ ─ ─
                  └─────┘               ▲         │         │ ┌─────┐
                             │     write│                   │ │Event│
                                        │         │         │ └─────┘
                             │ ┌────────────────┐           │
                               │  handle_event  │◀┼─────────┘
                             │ └────────────────┘
                                                  │
                             └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

The EventLog and SnapshotStore traits define a pluggable event log and a pluggable snapshot store respectively. For NATS and Postgres these are implemented in the respective crates.

EventSourcedEntity::spawn puts the event sourced entity on the given event log and snapshot store, returning an EntityRef which can be cheaply cloned and used to pass commands to the entity. Conversion of events and snapshot state to and from bytes happens via the given Binarize implementation; for prost and serde_json these are already provided. Snapshots are taken after the configured number of processed events to speed up future spawning.

EntityRef::handle_command either returns Command::Error for a rejected command or Command::Reply for an accepted one, wrapped in another Result dealing with technical errors.

Events can be queried from the event log by ID or by entity type. These queries can be used to build read side projections. There is early support for projections in the eventsourced-projection crate.

Modules

• binarize
  Conversion to and from Bytes.
• event_log
  Persistence for events.
• snapshot_store
  Persistence for snapshots.

Structs

• EntityRef
  A handle representing a spawned EventSourcedEntity, which can be used to pass it commands.
• EventSourcedEntity
  An EventSourcedEntity which can be spawned.
• HandleCommandError
  A technical error, signaling that a command cannot be sent from an EntityRef to its event sourced entity or the result cannot be received from its event sourced entity.

Enums

• CommandEffect
  The result of handling a command, either emitting an event and replying or rejecting the command.
• SpawnError
  A technical error when spawning an EventSourcedEntity.

Traits

• Command
  A command for a EventSourced implementation, defining command handling and replying.
• EventSourced
  State and event handling for an EventSourcedEntity.
• EventSourcedExt
  Extension methods for EventSourced entities.